feat(web): configuration-only optional frontend analytics (Umami + DataFinder) - #1037

Summary

Refs #989（两步交付的第二步。合并并验证后，可以关闭 #989）

按 #1010 合并时的约定和 OpenSpec openspec/changes/add-configurable-frontend-analytics/ 里的 PR-2 部分，把前端动作统计做成「改配置就能开」的可选功能。

• 只改配置：Docker／Compose 和 Helm 用户填两项配置就能开启：SKILLHUB_WEB_ANALYTICS_CONFIG（JSON：enabled、adapter、consent、rules、adapterConfig）和 SKILLHUB_WEB_ANALYTICS_UPSTREAM（统计平台地址，只在部署侧使用，不会下发到浏览器）。不需要改 JS、复制文件或手写 Nginx。
• 默认关闭、按需加载：页面挂载完成后才读取统计配置。没配置、enabled:false、consent:denied 或配置写错时，不加载采集模块和 SDK，也不发请求；页面启动不等待统计平台。
• 故障隔离：配置写错只关闭统计，容器日志只提示出错的字段名，不回显原值；其他 runtime-config 字段保持不变。统计平台域名在请求时才解析，解析失败或平台停机都不影响 Web 启动和业务。
• 单一产品源码：helper 和 Umami adapter 迁到 web/src/features/analytics/（通用类型、controller、loader、静态注册表、adapters/umami）。feat(web): add passive semantic analytics attributes across frontend workflows #1010 的两组测试一起迁入，断言没有改动。通用部分不认识 Umami 的字段，以后加平台只需新增一个注册的 adapter。
• 同源代理：Web 容器启动时，只在开启后生成 /_skillhub-analytics/ 代理。只放行 Umami 的 script.js 和 api/send，其他路径都返回 404，不暴露管理界面。HTTPS 上游会校验证书并带正确的 SNI；代理会去掉 Cookie、Authorization、Referer。保留前缀已同步到 20-base-path.sh、base-path-config.ts、validate-release-config.sh 和 Helm 校验。子路径部署可用。
• 没有新增依赖：没按设计稿引入 jq。用镜像自带的 awk 校验 JSON（限制 64 KiB、32 层、拒绝重复键），再用 base64 写进 runtime-config.js，浏览器端按数据解析。代价是多了一个约 90 行、有测试覆盖的小解析器。
• 部署接线：compose.release.yml、.env.release.example 和 Helm 的 values、schema、ConfigMap、Deployment 都已透传，默认关闭。新增可选的 compose.analytics-umami.yml，用来自托管 Umami 和它自己的 Postgres：必须显式提供密码，管理端口只绑本机，不额外增加 Nginx。
• 文档：docs/frontend-analytics-integration.md 改写成只改配置的中文接入指南，内容包括已有 Umami、自托管组合、动态授权、验收、排障、升级和关闭；docs/frontend-analytics.md 更新为英文契约。docs/examples/analytics/ 只保留一个指路说明。OpenSpec tasks.md 只勾选了本 PR 实际完成的项目。

第二个平台：DataFinder（火山引擎增长分析）

原在 #1050，按讨论合入本 PR（#1050 已关闭）。它和 Umami 共用同一套转换层、开关和代理框架，不涉及一键部署。

• 只改配置：adapter: "datafinder"，adapterConfig 只接受数字 appId 和可选的 product（默认 skillhub），upstream 填采集域名。其他字段全部拒绝，包括 App Key，防止误把服务端密钥放进前端。
• 不引入官方 SDK：官方 JS SDK 约 250 KB，而且不是开源许可。适配器直接用 fetch(keepalive) 发 DataFinder Web 上报的最小 /list 负载：一个 batch、一个事件。不批量等待，不持久化，不重试，每次最长 3 秒。
• 事件内容：事件名就是原有动作 ID（例如 skill.download.request），params 只含原生 event。公共属性只有 product 和 module：module 是动作所在页面的路由模板（例如 /space/$namespace/$slug），不含真实 namespace、slug、query 或 hash，未匹配的页面记为 other。
• 匿名标识：生成随机 UUID v4 作为 user_unique_id/web_id，存在 localStorage，用于按浏览器统计 UV。不绑定 SkillHub 账号。纯 HTTP 内网部署没有 crypto.randomUUID，改用 getRandomValues 生成。存储不可用时只在当前页用内存 ID。文档写明这不等于无身份数据，由部署方评估。
• 成功判定：只认 e:0 且 sc:1；HTTP 200 不算成功。
• 代理：只放行 POST /_skillhub-analytics/list，Umami 的端点返回 404。沿用 TLS 校验，并清除 Cookie、Authorization、Referer。保留浏览器 User-Agent，因为平台会拒收非浏览器 UA。
• 通用层改动：bootstrap 提供一个与平台无关的 currentPageType getter，依次经 loader、controller 传给 factory。Umami 不使用它。通用配置和 controller 不认识 DataFinder 的字段。awk 校验器增加数字值和按适配器分支。
• 文档：接入指南新增第 2.1 节，说明配置、Helm、核对步骤、排障表（UA 拒收、sc:0、502）和隐私边界；英文契约和 OpenSpec PR-3 任务同步更新。

一键部署与独立管理（维护者第二轮反馈）

• runtime.sh 两步部署：analytics-up 自动获取 compose.analytics-umami.yml，首次生成并保存独立密钥（<home>/analytics/.env，600 权限，已存在不覆盖），启动 Umami 和它自己的 Postgres，输出管理地址。用户改密、建网站拿到 UUID 后，运行 analytics-enable --website-id <UUID>：写入配置，Web 加入共享网络并重新创建。已有平台用 analytics-enable --website-id <UUID> --upstream <origin>，跳过第一步，也不建网络；DataFinder 用 --adapter datafinder --app-id <N> --upstream <origin>。另有 analytics-disable、analytics-down（只停止，不删卷）和 analytics-ps/logs/pull。
• 两个独立 Compose 项目：统计平台使用独立项目名和数据卷。只有 Web（经 compose.release.analytics.yml）和 Umami 加入外部网络 skillhub-analytics，网络由脚本幂等创建、由 Compose 声明。开启后普通 up 自动带上这层网络配置，Web 重建后仍然连接。clean 保留统计平台的密钥和文件。
• Kubernetes 独立部署单元：deploy/k8s/analytics-umami/umami.yaml 在独立 namespace 中部署 Postgres（PVC）、Umami 和两个 ClusterIP Service，Secret 由部署方创建。SkillHub Chart 只填写 web.analytics，经 Service DNS 连接，不依赖 Umami。
• 真实集群冒烟脚本：charts/skillhub/tests/analytics-smoke.sh 核对事件真实入库，并断言只改统计配置时 Web Pod 替换、Server Pod UID 不变。
• 文档：按三条路径分别说明：一键脚本新建平台、一键脚本接已有平台、Helm。写明文件如何获取、UUID 在哪一步取得、配置如何生效，以及关闭、升级和数据保留；运行边界保持不变。
• 测试清理：旧 PR 的静态 fixture（pr1-compose.yaml、pr1-nginx.conf）已删除，仍需要的约束改为断言当前生产配置。新增 scripts/tests/runtime-analytics-test.sh，已加入 CI。
• --aliyun：该模式从 OSS 根目录下载文件。OSS 目前没有新增的两个 Compose 文件（实测 404），需要在发布时同步上传，文档已写明。

Validation

基于最新 main（已合并 a681e43e 之后的 main），head ffc9c834。

corepack pnpm@10.33.0 -C web test        # 270 文件 / 1,432 项通过（含 DataFinder）
corepack pnpm@10.33.0 -C web typecheck   # 通过
corepack pnpm@10.33.0 -C web lint        # 通过
corepack pnpm@10.33.0 -C web build       # 通过
node web/scripts/analytics-manifest.mjs  # 通过，清单内容逐字节不变
python3 scripts/tests/web-analytics-test.py          # 10 项通过（启动脚本、配置序列化、恶意 JSON、代理片段）
bash scripts/tests/web-base-path-routing-test.sh     # 通过
bash scripts/tests/validate-release-config-test.sh   # 通过
bash scripts/tests/web-base-path-nginx-smoke-test.sh # 通过（真实 nginx 容器）
bash scripts/tests/nginx-forwarded-proto-test.sh     # 通过；结尾的 `ip_args[@]: unbound variable` 在 main 上同样出现，与本 PR 无关
helm lint --strict charts/skillhub -f charts/skillhub/tests/test-values.yaml   # 通过（helm 3.19.0 容器）
cd docs/skillhub && npm ci && npm run build                                  # 通过（站内 include 页含新内容）
bash charts/skillhub/tests/configuration-contracts.sh                        # 通过；含「只改统计仅 Web 更新、改后端配置后端仍更新」的 checksum 对照
docker compose --env-file .env.release.example -f compose.release.yml config
docker compose --env-file .env.release.example -f compose.release.yml -f compose.analytics-umami.yml config   # 需要提供密码，不提供时会按设计报错

一键部署实测（本机真实 Docker，隔离项目名和端口）：

• 空目录：runtime.sh up 后 Web 健康和业务 API 均为 200；analytics-up、建网站、analytics-enable 后，经同源代理发送事件 200，Umami API 和数据库都查到入库。
• 重复执行：analytics-up/up 前后密钥哈希、server 容器和事件数都不变。
• Web --force-recreate 后，默认网络和共享网络都还在，已存事件不变。
• analytics-down 时业务健康 200；再 analytics-up，数据还在。
• analytics-disable 后采集路由 404，业务 API 200。
• 已有平台：--upstream 接入后事件数 1 → 2，Web 没有加入本地统计网络。

真实集群（kind）： Umami/Postgres 部署在独立 stats namespace，SkillHub 是单独的 Helm Release。analytics-smoke.sh 结果：代理发送 200，Umami 数据库事件数 3 → 4。只改统计配置的 helm upgrade 替换了 Web Pod，Server Pod UID 不变。

限制：

• kind 中 Chart 固定的 Bitnami PostgreSQL 镜像在迁移 V65 报 could not compute MD5 hash: unsupported，这与本 PR 无关。集群验收改用独立的官方 postgres:16 + externalDatabase，所以不能说明固定镜像这条路径已通过。
• 入库验证用的是模拟浏览器 UA 的 HTTP 请求，没有做真实浏览器点击。
• 完整的 S3/auth 冒烟没有跑。

另外做了本地真实运行验收：用本 PR 构建的前端、仓库里的 Nginx 模板和启动脚本，配合 Umami 3.4.1 与 Postgres，在真实 Chrome 中完成 26 项检查，Umami 实际入库 9 条事件。检查覆盖：

• 默认零模块、零请求
• 开启后页面挂载完成才加载
• 实际出站请求只包含白名单字段
• 配置写错、adapter 未知、上游地址非法时，只关闭统计
• 域名无法解析、Umami 停机时，业务不受影响
• 未注册的代理路径返回 404
• 调用 stop() 后不再发送
• /skillhub/ 子路径部署
• 5 MiB 上传仍能到达 API

SkillHub 后端 API 是合成响应，不能作为后端业务的端到端证明。

还没覆盖的部分：

• 镜像离线构建时，Corepack 需要联网，所以没有在离线环境完成整镜像构建。真实运行验收使用同样的 dist、模板和启动脚本组装容器完成。
• OpenSpec 任务 6.3 中完整的 release Compose S3/auth 冒烟，以及 6.1、6.4 的评审和验收环节，都留给维护者。

Risk

• User-facing impact: 默认关闭，未配置时不加载采集代码、不发请求，行为和现在一致。
• Deployment or migration impact: Web 镜像新增一个启动脚本和一个 awk 文件，Compose 和 Helm 新增可选的环境变量；没有数据库或后端变更，也没有新增 npm、apk 依赖。/_skillhub-analytics/ 成为保留前缀，SKILLHUB_WEB_BASE_PATH 不能以它开头。修改配置后需要重新创建 Web（Compose 用 up -d --force-recreate web，restart 不会重新注入环境变量），新打开的页面才会生效；已经打开的旧标签页不会因关闭配置立即停止，需要刷新或关闭。Helm 的统计值放在 Web 专用 ConfigMap，只改统计配置时仅 Web 滚动更新，后端 Pod 不替换。
• Rollback approach: 清空 SKILLHUB_WEB_ANALYTICS_CONFIG 并重新创建 Web，新页面即完全关闭；回退镜像版本也可以。

Notes

• Related issue: [Feature] 支持厂商中立的前端业务语义属性 #989
• 新平台适配除了注册前端 adapter，还要在 Web 启动脚本加该平台的部署侧配置校验和精确代理端点，并补测试。
• 配置校验只检查格式：websiteId 是合法 UUID 但 Umami 中没有该网站时，api/send 返回 400 Website not found，事件不入库。排障表已补充。
• Follow-up work: 其他平台的 adapter 按需另提；一键部署统计平台另开 PR；本 PR 不包含后端业务事件（[Feature] RFC：默认关闭的厂商中立后端业务事件出口 / Opt-in backend business-event export #1009）、同意弹窗、重试队列或管理后台。
• Docs or operator runbooks updated when behavior changed: 已更新 docs/frontend-analytics-integration.md、docs/frontend-analytics.md、docs/09-deployment.md 和 chart README 的入口链接。